ATSUGetAllLayoutControls

OSStatus ATSUGetAllLayoutControls (
                     ATSUTextLayout iTextLayout,
                     ATSUAttributeInfo oAttributeInfoArray[],
                     ItemCount iTagValuePairArraySize,
                     ItemCount *oTagValuePairCount);

iTextLayout

A reference of type ATSUTextLayout. Pass a reference to a text layout object whose attribute information you want to obtain. You cannot pass NULL for this parameter.

oAttributeInfoArray

An array of structures of type ATSUAttributeInfo. Before calling ATSUGetAllAttributes, pass a pointer to memory that you have allocated for this array. If you are uncertain of how much memory to allocate, see the discussion below. On return, the array contains the tag and data size pairs corresponding to all previously set text layout attribute values in the text layout object.

iTagValuePairArraySize

The maximum number of tag and data size pairs in the text layout object. Typically, this is equivalent to the number of ATSUAttributeInfo structures in the oAttributeInfoArray array. To determine this value, see the discussion below.

oTagValuePairCount

A pointer to a count. On return, the actual number of ATSUAttributeInfo structures in the text layout object. This may be greater than the value you specified in the iTagValuePairArraySize parameter. You cannot pass NULL for this parameter.

function result

A result code. See Result Codes.

DISCUSSION

The ATSUGetAllLayoutControls function obtains an array of the tags and data sizes corresponding to all previously set text layout attribute values for an entire text layout object. You can obtain a particular attribute value by passing the corresponding tag and data size pair to the function ATSUGetLayoutControl. To obtain the tags and data sizes corresponding to all previously set text layout attribute values in a line of a text layout object, call the function ATSUGetAllLineControls.

The best way to use ATSUGetAllLayoutControls is to call it twice:

Pass a reference to the text layout object containing the attribute in the iTextLayout parameter, NULL for the oAttributeInfoArray parameter, and 0 for the other parameters. ATSUGetAllLayoutControls returns the size of the oAttributeInfoArray array in the oTagValuePairCount parameter.
Allocate enough space for an array of the returned size, then call the function again, passing a pointer in the oAttributeInfoArray parameter; on return, the pointer references the oAttributeInfoArray array.

VERSION NOTES

Available beginning with ATSUI 1.0.